TinyLogo Procedures

TinyLogo Version 1.1
(c) 1999 Timothy Lipetz
lipetz@netset.com

>>> Program Flow <<<
Proc|Alias|#Args|Return|Note
      output     | op | 1 | _ | Returns its arg to the calling procedure
      stop     | _ | 0 | _ | Returns to calling procedure with no return value
      halt     | _ | 0 | _ | Stops command execution 
      run     | _ | 1 | _ | Executes its argument(list)
      if     | _ | 2 | _ | If the first arg (logic) evaluates to true, executes its 2nd arg (list) 
      ifelse     | _ | 3 | _ | If the first arg (logic) evaluates to true, executes its 2nd arg (list) otherwise executes its 3rd arg (list) 
      repeat     | rep | 2 | _ | Executes its 2nd arg (list) n times where n is its 1st arg (number)
      repeatcount     | cnt | 0 | number | Within a repeat list, gives the current repetition count, starting at zero
      make     | mk | 2 | _ | Associates value of 2nd arg (any) with the global make-variable name given in its 1st arg (word). You must use thing to dereference the make-variable (the ":" notation is not supported.) There is a limit of 50 symbol names for the combination of make-variables and user-defined procedures.
      thing     | thg | 1 | any | Returns current value of the global make-variable with name given in its 1st arg (word). See make.
     
>>> Logic <<<
Proc|Alias|#Args|Return|Note
      both      | and  | 2 | logic ("true / "false) | Returns true if both args(logic) are true, else returns false 
      either      | or  | 2 | logic  | Returns true if either args(logic) is true, else returns false 
      greaterthan      | gt  | 2 | logic  | Returns true if the 1st arg (number, word) is > the 2nd. 
      greaterorequal      | ge  | 2 | logic  | Returns true if the 1st arg (number, word) is >= the 2nd. 
      lessthan      | lt  | 2 | logic  | Returns true if the 1st arg (number, word) is < the 2nd. 
      lessorequal      | le  | 2 | logic  | Returns true if the 1st arg (number, word) is <= the 2nd. 
      equal      | eq  | 2 | logic  | Returns true if the 1st arg (number, word, list) is equal to the 2nd. Note: for lists this should only be used to test against the empty list []. 
      notequal      | ne  | 2 | logic  | Returns true if the 1st arg (number, word, list) is not equal to the 2nd. Note: for lists this should only be used to test against the empty list []. 
      not      | _  | 1 | logic  | Returns the opposite of its arg (logic) 
      false     | f | 0 | false | Constant false
      true     | t | 0 | true | Constant true
      isnumber      | isnm  | 1 | logic  | Returns true if its arg is a number 
      isword      | iswd  | 1 | logic  | Returns true if its arg is a word 
      islist      | _  | 1 | logic  | Returns true if its arg is a list 

>>> Arithmetic <<< 
Proc|Alias|#Args|Return|Note
      sum     | _ | 2 | number | Returns 1st arg plus 2nd (numbers) 
      difference     | dif | 2 | number | Returns 1st arg minus 2nd (numbers) 
      product     | prd | 2 | number | Returns 1st arg times 2nd (numbers) 
      quotient      | quo | 2 | number | Returns 1st arg divided by 2nd (numbers) 
      modulo     | mod | 2 | number | Returns the remainder of 1st arg divided by 2nd (numbers) 
      random     | rnd | 1 | number | Returns a random number less than its arg (number) and greater than or equal to 0. 
      add1     | _ | 1 | number | Returns its arg (number) plus one
      sub1     | _ | 1 | number | Returns its arg (number) minus one

>>> Lists and Words <<< 
Proc|Alias|#Args|Return|Note
      first     | fi | 1 | word / any | Returns the first letter of a word, or the first item in a list
      last     | la | 1 | word / any | Returns the last letter of a word, or the last item in a list
      butfirst     | bf | 1 | word / list | Returns all but the first letter of a word, or all but the first item in a list
      butlast     | bl | 1 | word / list | Returns all but the last letter of a word, or all but the last item in a list
      length     | len | 1 | number | Returns the number of letters in a word or the number of items in a list
      sentence     | se | 2 | list | Returns a list formed by its two args (any)
      word     | wd | 2 | word | Returns the concatenation of its two args (words or numbers). Numbers are converted to text.
      tonum     | _ | 1 | number | Returns the numeric value of its arg (word) This is useful with readline.

>>> Turtle Graphics <<< 
Proc|Alias|#Args|Return|Note
      turtle     | tu | 0 | _ | Enters Turtle Mode
      noturtle     | ntu | 0 | _ | Leaves Turtle Mode
      clearscreen     | cs | 0 | _ | Clears screen (in Turtle Mode)
      home     | _ | 0 | _ | Move Turtle to center screen (0,0) and heading up (90 degrees)
      showturtle     | st | 0 | _ | Displays Turtle triangle
      hideturtle     | ht | 0 | _ | Hides Turtle triangle
      pendown     | pd | 0 | _ | Pen is down - Turtle will leave trail
      penup     | pu | 0 | _ | Pen is up - Turtle will not leave trail
      pennormal     | pn | 0 | _ | Pen writes in black
      penerase     | pe | 0 | _ | Pen writes in white
      penreverse     | pr | 0 | _ | Pen reverses black and white
      turtlex     | tx | 0 | number | Returns X location of turtle. Where center screen is 0, left is -80, right is +80.
      turtley     | ty | 0 | number | Returns Y location of turtle. Where center screen is 0, bottom is -80, top is +80.
      turtleheading     | th | 0 | number | Returns Turtle heading in degrees. Where right is 0, up is 90, etc.
      forward     | fd | 1 | _ | Turtle moves forward arg (number) pixels
      back     | bk | 1 | _ | Turtle moves backward arg (number) pixels
      left     | lf | 1 | _ | Turtle turns left arg (number) degrees
      right     | rt | 1 | _ | Turtle turns right arg (number) degrees
      setheading     | sh | 1 | _ | Turtle turns to face arg (number) heading (see th) 
      setx     | sx | 1 | _ | Turtle moves in X to arg (number) location, drawing if pen is down.
      sety     | sy | 1 | _ | Turtle moves in Y to arg (number) location, drawing if pen is down.
      setxy     | sxy | 2 | _ | Turtle moves in X and Y to args (numbers) location, drawing if pen is down.
      box     | _ | 4 | _ | Draws a filled rectangle. Args are X, Y, Width, Height, where the X, Y is upper left corner. The rectangle is filled based on current penmode (pennormal, penerase, penreverse )
      printtext     | pt | 3 | _ | Displays 1st arg (word or list) at X, Y of 2nd and 3rd args (numbers).
      icon     | _ | 3 | _ | Displays icon with ID 1st arg (number) at X, Y of 2nd and 3rd args (numbers). Icon IDs are 0-49 See loadicons.
      loadicons     | li | 1 | _ | Loads an icon definition memo with arg (word) as its title. Be sure to quote " the memo name. - Do not use if a memo is currently openned with mopen or mnew. See icon. Also see Icon File Format below.

>>> Icon File Format <<<

The icon file used by loadicons, has a strict format.

- The first line is the title (as required by the Palm OS) 
- The second line is a required comment - this line must be present. 
- Each remaining line represents a single icon. There can be up to 50 icons defined at a time. Each line must be formatted as: 
  - The first two characters are the icon ID as digits from 00 to 49. Use two digits even for numbers less than ten. 
  - The third character is an underscore "_" 
  - The last character is a period "." 
  - The characters between the underscore and period follow the PocketC bitmap format which is a list of hexadecimal digits in the following form: "wwxxxxxxxx..." where 'ww' is the width of the bitmap (i.e. '0a' is a 10-pixel wide bitmap), and 'xxx...' are the bits of the bitmap, each character representing 4 pixels 
  - Note: a long icon definition can be continued over the next several lines (no spaces). The icon definition is understood to continue until the period is encountered even if that is several lines later. 

An example of an icon definition would be (from PocketC manual):

Example: A 10x4 rectangle "0affc804804ffc"

8 4 2 1 8 4 2 1 8 4 2 1
X X X X X X X X X X 0 0 = ffc
X 0 0 0 0 0 0 0 0 X 0 0 = 804
X 0 0 0 0 0 0 0 0 X 0 0 = 804
X X X X X X X X X X 0 0 = ffc

A simple example icon definition file, called "myicons", would be these three lines:

myicons

icon 5 is a small rectangle

05_0affc804804ffc.

>>> Sound <<<
Proc|Alias|#Args|Return|Note
      tone     | _ | 2 | _ | Plays a tone of 1st arg (number) Hz. for 2nd arg (number) / 100 seconds.
      beep     | _ | 1 | _ | Plays the Palm defined system sound, based on arg (number). Sounds are info[1], warning[2], error[3], startup[4], alarm[5], confirmation[6], and click[7].
      note     | _ | 2 | _ | Plays a music note for 2nd arg (number) / 100 seconds. The notes are a diatonic scale with 1st arg (number) = 0 for middle C, = 1 for C#, = 2 for D, ..., = 12 for high C, etc. On my PalmPilot, the usable range seems to be 9 octaves from -48 to 60. (Although the low notes do rattle!)

>>> Program Input/Output <<< 
Proc|Alias|#Args|Return|Note
      print     | p | 1 | _ | Displays its arg (any) followed by a space. In Turtle Mode, this uses a popup dialog which blocks until user selects "Okay." Otherwise, it is non-blocking.
      printline     | pl | 1 | _ | Displays its arg (any) followed by a newline. In Turtle Mode, this uses a popup dialog which blocks until user selects "Okay." Otherwise, it is non-blocking.
      readline     | rl | 1 | list of words | Presents user with a popup dialog showing its arg (list) as a prompt. It blocks waiting for input, then returns input as a list of words. (see tonum, above)
      ask     | _ | 1 | logic | Presents user with a popup dialog showing its arg (list or word) as a prompt and "Yes" and "No" buttons. Returns true if user picks "Yes" else returns false.
	readpen     | rp | 0 | _ | Blocks, waiting for user to tap screen, then continues. (see penx, 
peny) While waiting for input in Turtle Mode, it will show a "??" prompt in bottom left corner.
      pen     | _ | 0 | logic | Returns true immediately if the Palm screen detects a pen, else returns false immediately. Sets penx and peny if true (see penx, peny)
      penx     | px | 0 | number | Returns the X location of the pen at the last readpen 
      peny     | py | 0 | number | Returns the Y location of the pen at the last readpen 
      in     | _ | 4 | logic  | Returns true if the last set penx and peny are within the rectangle defined by args (numbers) X, Y, Width, Height.
      mopen     | _ | 1 | _ | Opens an existing Palm memo with arg (word or list) as a title.
      mnew     | _ | 1 | _ | Creates a new Palm memo with arg (word or list) as a title.
      mclose     | _ | 0 | _ | Closes the currently open memo.
      mprint     | mp | 1 | _ | Prints arg (any) followed by a space to end of open memo.
      mprintline     | mpl | 1 | _ | Prints arg (any) followed by a newline to end of open memo.
      mreadline     | mrl | 0 | list of words  | Returns current memo line as a list of words, then advances to next line.
      meof     | _ | 0 | logic | Returns true if read buffer is at end of current memo. 

>>> TinyLogo Workspace <<< 
Proc|Alias|#Args|Return|Note
      load     | ld | 1 | _ | Loads a TinyLogo memo from the Palm memopad. The memo's first line must be "TL_" followed by the arg (word). The memo should contain TinyLogo procedure definitions. - Be sure to quote " the memo name.
      printproc     | pp | 1 | _ | Displays the definition of a user defined procedure named as arg (word). - Be sure to quote " the procedure name.
      saveproc     | sp | 2 | _ | Appends the procedure named in 1st arg (word) to memo named in 2nd arg (word), where 2nd arg should not contain the implied "TL_" prefix.- Be sure to quote " both args.
      listprocs     | lp | 0 | _ | Displays the names of all user defined procedures in TinyLogo.
      listmemos     | lm | 0 | _ | Displays the names of all Palm memos starting "TL_"
      nodes     | _ | 0 | number | Returns the number of nodes available for use at that moment.
      garbagecollect     | gc | 0 | _ | Forces a garbage collection at the next opportunity.
      help     | _ | 0 | _ | Displays names and aliases for all built-in procedures
      to     | _ | 0 | _ | Starts procedure definition. There is a limit of 50 symbol names for the combination of make-variables and user-defined procedures.
      end     | _ | 0 | _ | Ends procedure definition
